==============================================================
  VULNERD — Automated Security Report Card Engine
==============================================================

  "Know your grade. Fix your gaps. Protect your network."

--------------------------------------------------------------
WHAT IS VULNERD?
--------------------------------------------------------------
Vulnerd transforms raw Nessus vulnerability scan data into
easy-to-understand security report cards. Using a familiar
school-grade metaphor (A through F), Vulnerd scores your
network's security posture, generates plain-English AI
analysis, maps findings to compliance frameworks, and
delivers polished PDF reports straight to your inbox.

Whether you're a small business owner, IT admin, or security
analyst, Vulnerd makes complex vulnerability data accessible
to everyone — no security degree required.

--------------------------------------------------------------
KEY FEATURES
--------------------------------------------------------------
  - Letter-grade scoring (A-F) based on vulnerability counts
  - AI-powered analysis via Google Gemini (plain English)
  - Single-scan reports AND multi-scan trend analysis
  - Compliance framework mapping:
      Healthcare  -> HIPAA
      Retail      -> PCI-DSS
      Government  -> NIST 800-53
      Education   -> FERPA
      General     -> CIS Controls
  - Professional PDF report generation
  - Email delivery of reports to stakeholders
  - Interactive web UI with drag-and-drop CSV upload
  - AI chatbot for Q&A about your scan results
  - Command-line interface for headless/automated use
  - Runs on Windows PCs or Raspberry Pi / Linux servers

--------------------------------------------------------------
REQUIREMENTS
--------------------------------------------------------------
  - Python 3.10 or higher
  - pip (Python package installer)
  - A Google Gemini API key (free tier available)
  - A Gmail account with App Password enabled (for email)
  - Nessus vulnerability scan exported as CSV

  Install dependencies:
      pip install -r requirements.txt

--------------------------------------------------------------
QUICK START (WINDOWS)
--------------------------------------------------------------
  1. Double-click "Start Vulnerd.bat"
     - This opens a browser to http://localhost:5001
  2. Drag and drop your Nessus CSV file into the upload zone
  3. (Optional) Select your business type for compliance context
  4. Click "Grade My Network"
  5. Review your grade card and AI-generated analysis
  6. (Optional) Enter an email address to receive a PDF report

  For detailed setup instructions, see: INSTRUCTIONS.txt

--------------------------------------------------------------
QUICK START (COMMAND LINE / CLI)
--------------------------------------------------------------
  1. Place your Nessus CSV file(s) in the ./evidence_locker/ folder
  2. Run:  python vulnerd.py
  3. Choose analysis mode:
       [1] Single Report   — analyze one scan
       [2] Trend Analysis  — compare multiple scans over time
  4. Enter a recipient email address
  5. Vulnerd generates and emails the PDF report automatically

--------------------------------------------------------------
HOW TO USE — WEB UI WORKFLOWS
--------------------------------------------------------------
  SINGLE SCAN ANALYSIS:
    - Upload one CSV file
    - Select mode: "Single Scan Report"
    - Choose business type (optional)
    - Click "Grade My Network"
    - View grade, severity breakdown, and AI analysis sections:
        * Executive Summary
        * Key Findings
        * Contributing Factors
        * Recommendations
        * Threat Context
        * Who to Call
        * Instructor's Note

  TREND ANALYSIS (Multi-Scan):
    - Upload two or more CSV files
    - Select mode: "Trend Analysis"
    - Click "Grade My Network"
    - View scan-by-scan progress and improvement patterns

  CHAT WITH VULNERD:
    - After running an analysis, click the chat button
      (bottom-right corner)
    - Ask questions about your results in plain English
    - Vulnerd uses AI to answer based on your specific scan data

--------------------------------------------------------------
GRADING SCALE
--------------------------------------------------------------
  Score   Grade   Meaning
  ------  -----   -----------------------------------------------
  93-100   A      Excellent security posture
  90-92    A-     Really strong results
  87-89    B+     Good job, above average
  83-86    B      Solid foundation
  80-82    B-     Passing, with a clear improvement path
  77-79    C+     Real work to do
  73-76    C      Meaningful exposure, needs prompt attention
  70-72    C-     Critical/High items are urgent
  67-69    D+     High-priority items need immediate action
  63-66    D      Urgent remediation needed
  60-62    D-     Immediate escalation recommended
  < 60      F     Serious exposure — escalate today

  Scoring deductions per vulnerability:
    Critical: -20 pts   High:   -8 pts
    Medium:    -3 pts   Low:    -1 pt
    (Starting score: 100, minimum score: 0)

--------------------------------------------------------------
COMPLIANCE FRAMEWORKS
--------------------------------------------------------------
  Vulnerd maps your findings to industry compliance standards
  based on your organization type:

    Business Type     Framework
    ---------------   ---------------------------------
    Healthcare        HIPAA (Health data protection)
    Retail/Payments   PCI-DSS (Payment card security)
    Government        NIST 800-53 (Federal standards)
    Education         FERPA (Student data protection)
    General Business  CIS Controls (Best practices)

  The compliance panel shows:
    - Framework-specific risk attributes
    - Risk scores per attribute
    - Real-world impact estimates
    - Remediation cost vs. breach cost analysis

--------------------------------------------------------------
CONFIGURATION (.env FILE)
--------------------------------------------------------------
  Edit the .env file in the project folder to set your keys:

    GEMINI_API_KEY=your_gemini_api_key_here
    OPENAI_API_KEY=                         (optional fallback)
    EMAIL_SENDER=your_gmail@gmail.com
    EMAIL_PASSWORD=your_gmail_app_password
    SMTP_SERVER=smtp.gmail.com
    SMTP_PORT=465

  To get a Gemini API key: https://aistudio.google.com
  To set up a Gmail App Password:
    Google Account > Security > 2-Step Verification > App Passwords

--------------------------------------------------------------
PROJECT FILES
--------------------------------------------------------------
  app.py                  Web server (run this for the UI)
  vulnerd.py              Command-line interface version
  templates/index.html    Web application frontend
  requirements.txt        Python package dependencies
  .env                    API keys and email configuration
  Start Vulnerd.bat       Windows launcher (double-click to run)
  vulnerd.service         Systemd service file (Linux/Pi auto-start)
  INSTRUCTIONS.txt        Detailed setup guide for Windows users
  RASPBERRY_PI_SETUP.txt  Deployment guide for Raspberry Pi/Linux
  vulnerd.ico             Application icon

--------------------------------------------------------------
DEPLOYMENT ON RASPBERRY PI / LINUX SERVER
--------------------------------------------------------------
  Vulnerd can run as a persistent background service on a
  Raspberry Pi or Ubuntu server, accessible to all devices
  on your network.

  See: RASPBERRY_PI_SETUP.txt for full instructions.

  Once running, access the web UI from any device at:
      http://<server-ip>:5001

--------------------------------------------------------------
TROUBLESHOOTING
--------------------------------------------------------------
  "Python not found"
    -> Install Python 3.10+ from https://python.org
    -> Check "Add Python to PATH" during installation

  "Module not found" errors
    -> Run: pip install -r requirements.txt

  "API error" or no AI analysis generated
    -> Verify your GEMINI_API_KEY in the .env file
    -> Check your internet connection

  "Email not sending"
    -> Confirm EMAIL_SENDER and EMAIL_PASSWORD in .env
    -> Use a Gmail App Password (not your regular password)
    -> Ensure 2-Step Verification is enabled on your Gmail

  For more help, see INSTRUCTIONS.txt

--------------------------------------------------------------
VERSION INFO
--------------------------------------------------------------
  Project:  Vulnerd
  Platform: Windows / Linux / Raspberry Pi
  Language: Python 3.10+
  AI Model: Google Gemini 2.5-flash (with fallback chain)
  Port:     5001 (default)

==============================================================
